<?php
/**
 * @author Tongle Xu <xutongle@gmail.com>
 * @copyright Copyright (c) 2003-2103 Jinan TintSoft development co., LTD
 * @license http://www.tintsoft.com/html/about/copyright/
 * @version $Id$
 */
namespace Leaps\Web;

use ArrayIterator;
use Leaps\Base\InvalidCallException;
use Leaps\Base\Object;

/**
 * CookieCollection maintains the cookies available in the current request.
 *
 * @property integer $count The number of cookies in the collection. This
 * property is read-only.
 * @property ArrayIterator $iterator An iterator for traversing the cookies in
 * the collection. This property
 * is read-only.
 *
 * @author Tongle Xu <xutongle@gmail.com>
 * @since 4.0
 */
class CookieCollection extends Object implements \IteratorAggregate, \ArrayAccess, \Countable {
	/**
	 *
	 * @var boolean whether this collection is read only.
	 */
	public $readOnly = false;

	/**
	 *
	 * @var Cookie[] the cookies in this collection (indexed by the cookie
	 * names)
	 */
	private $_cookies = [ ];

	/**
	 * Constructor.
	 *
	 * @param array $cookies the cookies that this collection initially
	 * contains. This should be
	 * an array of name-value pairs.s
	 * @param array $config name-value pairs that will be used to initialize the
	 * object properties
	 */
	public function __construct($cookies = [], $config = []) {
		$this->_cookies = $cookies;
		parent::__construct ( $config );
	}

	/**
	 * Returns an iterator for traversing the cookies in the collection.
	 * This method is required by the SPL interface `IteratorAggregate`.
	 * It will be implicitly called when you use `foreach` to traverse the
	 * collection.
	 *
	 * @return ArrayIterator an iterator for traversing the cookies in the
	 * collection.
	 */
	public function getIterator() {
		return new ArrayIterator ( $this->_cookies );
	}

	/**
	 * Returns the number of cookies in the collection.
	 * This method is required by the SPL `Countable` interface.
	 * It will be implicitly called when you use `count($collection)`.
	 *
	 * @return integer the number of cookies in the collection.
	 */
	public function count() {
		return $this->getCount ();
	}

	/**
	 * Returns the number of cookies in the collection.
	 *
	 * @return integer the number of cookies in the collection.
	 */
	public function getCount() {
		return count ( $this->_cookies );
	}

	/**
	 * Returns the cookie with the specified name.
	 *
	 * @param string $name the cookie name
	 * @return Cookie the cookie with the specified name. Null if the named
	 * cookie does not exist.
	 * @see getValue()
	 */
	public function get($name) {
		return isset ( $this->_cookies [$name] ) ? $this->_cookies [$name] : null;
	}

	/**
	 * Returns the value of the named cookie.
	 *
	 * @param string $name the cookie name
	 * @param mixed $defaultValue the value that should be returned when the
	 * named cookie does not exist.
	 * @return mixed the value of the named cookie.
	 * @see get()
	 */
	public function getValue($name, $defaultValue = null) {
		return isset ( $this->_cookies [$name] ) ? $this->_cookies [$name]->value : $defaultValue;
	}

	/**
	 * Returns whether there is a cookie with the specified name.
	 *
	 * @param string $name the cookie name
	 * @return boolean whether the named cookie exists
	 */
	public function has($name) {
		return isset ( $this->_cookies [$name] );
	}

	/**
	 * Adds a cookie to the collection.
	 * If there is already a cookie with the same name in the collection, it
	 * will be removed first.
	 *
	 * @param Cookie $cookie the cookie to be added
	 * @throws InvalidCallException if the cookie collection is read only
	 */
	public function add($cookie) {
		if ($this->readOnly) {
			throw new InvalidCallException ( 'The cookie collection is read only.' );
		}
		$this->_cookies [$cookie->name] = $cookie;
	}

	/**
	 * 删除一个cookie。
	 * If `$removeFromBrowser` is true, the cookie will be removed from the
	 * browser.
	 * In this case, a cookie with outdated expiry will be added to the
	 * collection.
	 *
	 * @param Cookie|string $cookie the cookie object or the name of the cookie
	 * to be removed.
	 * @param boolean $removeFromBrowser whether to remove the cookie from
	 * browser
	 * @throws InvalidCallException if the cookie collection is read only
	 */
	public function remove($cookie, $removeFromBrowser = true) {
		if ($this->readOnly) {
			throw new InvalidCallException ( 'The cookie collection is read only.' );
		}
		if ($cookie instanceof Cookie) {
			$cookie->expire = 1;
			$cookie->value = '';
		} else {
			$cookie = new Cookie ( [ 'name' => $cookie,'expire' => 1 ] );
		}
		if ($removeFromBrowser) {
			$this->_cookies [$cookie->name] = $cookie;
		} else {
			unset ( $this->_cookies [$cookie->name] );
		}
	}

	/**
	 * 删除所有cookie。
	 *
	 * @throws InvalidCallException if the cookie collection is read only
	 */
	public function removeAll() {
		if ($this->readOnly) {
			throw new InvalidCallException ( 'The cookie collection is read only.' );
		}
		$this->_cookies = [ ];
	}

	/**
	 * 返回集合作为一个PHP数组。
	 *
	 * @return array the array representation of the collection.
	 * The array keys are cookie names, and the array values are the
	 * corresponding
	 * cookie objects.
	 */
	public function toArray() {
		return $this->_cookies;
	}

	/**
	 * Returns whether there is a cookie with the specified name.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like
	 * `isset($collection[$name])`.
	 *
	 * @param string $name the cookie name
	 * @return boolean whether the named cookie exists
	 */
	public function offsetExists($name) {
		return $this->has ( $name );
	}

	/**
	 * Returns the cookie with the specified name.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `$cookie =
	 * $collection[$name];`.
	 * This is equivalent to [[get()]].
	 *
	 * @param string $name the cookie name
	 * @return Cookie the cookie with the specified name, null if the named
	 * cookie does not exist.
	 */
	public function offsetGet($name) {
		return $this->get ( $name );
	}

	/**
	 * Adds the cookie to the collection.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `$collection[$name] =
	 * $cookie;`.
	 * This is equivalent to [[add()]].
	 *
	 * @param string $name the cookie name
	 * @param Cookie $cookie the cookie to be added
	 */
	public function offsetSet($name, $cookie) {
		$this->add ( $cookie );
	}

	/**
	 * Removes the named cookie.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like
	 * `unset($collection[$name])`.
	 * This is equivalent to [[remove()]].
	 *
	 * @param string $name the cookie name
	 */
	public function offsetUnset($name) {
		$this->remove ( $name );
	}
}
